Understanding Update Maps

An update map allows you to easily update your logical entity data service without having to write Java or XQSE code. This overview provides a foundation for understanding what an update map is and how you can use one.

BEA XQuery Scripting Extension (XQSE)

ALDSP generates a default update map automatically when you create a logical entity data service with a primary read function. You can see the update map associated with a data service by clicking the "Update Map" tab at the bottom of the screen (see the example that follows; click to enlarge image).

Example: a simple update map

In this overview, as a running example we use an update map for a data service that joins together customers and orders. This example may be downloaded if you wish to know the details of the data service that are not covered here. CustomerOrders.zip The image to the left shows the update map for the data service (CustomerOrders.ds). The orange arrow identifies the location of the "Update Map" tab.

An update map procedure is a create, update, or delete procedure that is implemented by an update map. The update map maps values from the input to the update map procedure to the inputs of the procedures in the underlying data services. These underlying data services that the logical entity data service is composed of are referred to as the source data services. In the previous example, the input is mapped to the two source data services CUSTOMER and ORDERS. The blue arrows in the update map show how the values are mapped.

A logical entity data service has a target type that describes the entity that the data service is about. All read functions in the data service must return instances of the target type and all update map procedures must accept instances of the target type as input. For example, say that we have an entity data service about customers. The read functions of this data service must return customers and update map procedures must take customers as input.

The Target Box

The target box displays the data type of the input to the update map procedures and the procedure icons. There is always exactly one target block in an update map and it is displayed on the right.

Example: the target box

The image to the left shows the update map for the data service CustomerOrders.ds. The target box is identified by the orange rectangle on the right. The procedure icons are in the upper-right corner of the target box. In this case they all contain a green check which indicates that the create, update, and delete update map procedures will function correctly. The input type to the procedures is shown below the procedure icons.

The input type
The input type (or, target type) is the type of the data that is passed to the update map procedures. Elements and attributes from the input type are mapped to the update blocks on the left.

Procedure icons
The Create , Update , and Delete procedure icons indicate the status of the corresponding update map procedures. They appear in the upper-right corner of the target box. Each icon may have a green check, a yellow exclamation or a red 'X'. A green check indicates that the update map is fully capable of implementing the procedure. A yellow exclamation indicates that you can invoke the procedure, but there may be problems at runtime. A red 'X' indicates there is a serious problem that needs to be addressed. Any time that there is a red 'X' or a yellow exclamation on the icon, you can hover the mouse pointer over the icon to get a tool tip providing more information (see the image below).

For Each Blocks

A for each block loops over elements in the input to the update map procedure. A for each block is associated with a variable and a path expression. The path expression defines the sequence to iterate over and the variable binds to elements in the sequence. The variable may be referenced by expressions inside the for each block.

Example: for each blocks

The image to the left shows the update map for the data service CustomerOrders.ds. The two orange arrows identify the two for each blocks in the map. The blocks are grey and have the title "For Each" followed by the variable name. The second for each block titled "For Each $order" is currently selected (to select a for each block, click on it). The orange rectangle identifies the properties of the currently selected for each block. In this case we see that it defines the variable $order which iterates over the sequence $customer/order.  $customer is a variable defined by the upper for each block.

Update Blocks

An update block invokes the primary create, update, or delete procedure of a source data service. It will invoke a procedure every iteration of the for each block that contains it. The contents of the update block represent the type of the input given to the procedure. Each element and attribute in the update block is assigned a mapping expression that determines what its value will be when the procedure is invoked. You can select an element or attribute to view or change the expression that determines what value it receives when the procedure is invoked (see the example below).

Procedure icons
Like the target box, an update block also has a procedure status icon. Here the icons indicate the ability of the update block to propagate creates, updates, and deletes to the underlying data service. Otherwise, the meaning of the icons is the same as it is for the target box.

Output variable
A primary create procedure may return a key. If the update block invokes a primary create procedure, it will bind the returned key to the output variable (also referred to as the key variable). The purpose of having the output variable available is for cases when the key value is generated automatically by an external source but is not part of the input. For example, your source data service is a wrapper for a customers relational database table. Say that the key of this table is an attribute CUSTOMER_ID which is an auto-generated number. If you are inserting a customer and some orders at the same time, you may need the auto-generated value for CUSTOMER_ID to pass to the input of the create procedure for ORDERS. When an update block results in the underlying update or delete procedure being invoked, the output variable will bind to the empty sequence.

Condition
An update block can optionally have a condition. The condition is a Boolean expression that determines if the update block should be invoked or not. If there is no condition, then the update block will always be invoked (see the example below).

Dependencies
When two or more update blocks appear as siblings within the same for-each block, it may be desirable to specify dependencies between them (e.g., due to referential constraints), so an update block can also include a list of dependencies. If update block A depends on update block B, update block B will execute before update block A in the case of a create or update operation (and in the opposite order in the case of a delete). Dependencies between update blocks that are not within the same for each block are not necessary, as the execution of an update map is implicitly outside-in.

Disabling an update block
An update block can be disabled so that it will never be invoked at runtime. You can disable an update block by right clicking on it and selecting "Disable" The update block should then appear yellow instead of white to indicate that it has been disabled. Disabling an update block is effectively the same as adding a condition that is always false.

Example: update blocks

The images to the left show the update map for the data service CustomerOrders.ds. In the first image, the two orange arrows identify the two update blocks in the map. One update map is for the source data service CUSTOMER and the other is for ORDERS. In this case, the ORDERS update block is selected and its details are identified by the orange rectangle (select an update block by clicking on it). We can see that the output variable for this update operation is $ORDERS_key. The condition is set to fn-bea:value($order/status) eq "OPEN" which means that this update block will only be executed when the input element status has the value "OPEN". $order is a variable that is defined by the for each block containing the update block ("For Each $order").

In the second image, the orange arrow identifies the ORDER_TOTAL element of the ORDERS update block. The orange rectangle identifies the mapping expression ($fn-bea:value($order/total)) for ORDER_TOTAL which is displayed because ORDER_TOTAL is currently selected. The ORDER_TOTAL element will receive the value of the total element when the source data service procedure is invoked.

The Return Key Block

The key block describes what will be returned by the update map create procedure. If the data service does not have a key specified, then there will not be a key block and there will never be more than one key block for an update map.

Example: the return key block

The image to the left shows the update map for the data service CustomerOrders.ds. The orange arrow identifies the key block in the update map. The key specified for the CustomerOrders data service is the element CID so the key block constructs the CID element to be returned and uses the output variable of the CUSTOMER update block to get the value.

Customization

ALDSP generates a default update map automatically when you create a logical entity data service with a primary read function. This default update map is generated based on the primary read function of the data service. As you change the primary read function, the update map will be regenerated automatically. However, if you customize (change) the update map then it will no longer be regenerated. In other words, a customized update map will no longer change along with the primary read function.

There are many different ways to customize an update map. See the following topics for more information:
Change a Mapping
Remove a Mapping
Revert Customizations
Edit XQuery Expressions
Add a Condition to an update block

Example

The image to the left shows the update map for the data service CustomerOrders.ds. The orange arrow identifies the "customized" symbol that appears after something in the update map has been changed. In this case, it is the mapping expression for ORDER_STATUS that has been modified.